<div class="tmd-doc">
<h1 class="tmd-header-1">
Memory Layouts
</h1>
<p></p>
<p></p>
<div class="tmd-usual">
This articles will introduce type alignment and size guarantees in Go. It is essential to know the guarantees to estimate the sizes of struct types and properly use the 64-bit functions in <code class="tmd-code-span">sync/atomic</code> standard package.
</div>
<p></p>
<div class="tmd-usual">
Go is a C family language, so many concepts talked in this article are shared with C language.
</div>
<p></p>
<h3 id="alignment-guarantee" class="tmd-header-3">
Type Alignment Guarantees in Go
</h3>
<p></p>
<div class="tmd-usual">
To fully utilize CPU directives and get the best performance, the (starting) addresses of the memory blocks allocated for values of a specified type must be aligned as multiples of an integer N, then N is called the value address alignment guarantee of the type, or simply the alignment guarantee of the type. We can also say the addresses of addressable values of the type are guaranteed to be N-byte aligned.
</div>
<p></p>
<div class="tmd-usual">
In fact, each type has two alignment guarantees, one is for when it is used as field types of other (struct) types, the other is for other cases (when it is used for a variable declaration, array element type, etc). We call the former one the field alignment guarantee of that type, and call the latter one the general alignment guarantee of that type.
</div>
<p></p>
<div class="tmd-usual">
For a type <code class="tmd-code-span">T</code>, we can call <code class="tmd-code-span">unsafe.Alignof(t)</code> to get its general alignment guarantee, where <code class="tmd-code-span">t</code> is a non-field value of type <code class="tmd-code-span">T</code>, and call <code class="tmd-code-span">unsafe.Alignof(x.t)</code> to get its field alignment guarantee, where <code class="tmd-code-span">x</code> is a struct value and <code class="tmd-code-span">t</code> is a field value of type <code class="tmd-code-span">T</code>.
</div>
<p></p>
<div class="tmd-usual">
Calls to the functions in the <code class="tmd-code-span">unsafe</code> standard code packages are always evaluated at compile time.
</div>
<p></p>
<div class="tmd-usual">
At run time, for a value <code class="tmd-code-span">t</code> of type <code class="tmd-code-span">T</code>, we can call <code class="tmd-code-span">reflect.TypeOf(t).Align()</code> to get the general alignment guarantee of type <code class="tmd-code-span">T</code>, and call <code class="tmd-code-span">reflect.TypeOf(t).FieldAlign()</code> to get the field alignment guarantee of type <code class="tmd-code-span">T</code>.
</div>
<p></p>
<div class="tmd-usual">
For the current standard Go compiler (v1.25.n), the field alignment guarantee and the general alignment guarantee of a type are always equal. For gccgo compiler, the statement is false.
</div>
<p></p>
<div class="tmd-usual">
Go specification only mentions <a href="https://golang.org/ref/spec#Size_and_alignment_guarantees">a little on type alignment guarantees</a>:
</div>
<div class="tmd-quotation">
<div class="tmd-usual">
The following minimal alignment properties are guaranteed:<br/>1. For a variable <code class="tmd-code-span">x</code> of any type: <code class="tmd-code-span">unsafe.Alignof(x)</code> is at least <code class="tmd-code-span">1</code>.<br/>2. For a variable <code class="tmd-code-span">x</code> of struct type: <code class="tmd-code-span">unsafe.Alignof(x)</code> is the largest of all the values <code class="tmd-code-span">unsafe.Alignof(x.f)</code> for each field <code class="tmd-code-span">f</code> of <code class="tmd-code-span">x</code>, but at least <code class="tmd-code-span">1</code>.<br/>3. For a variable <code class="tmd-code-span">x</code> of array type: <code class="tmd-code-span">unsafe.Alignof(x)</code> is the same as the alignment of a variable of the array's element type.
</div>
</div>
<p></p>
<p></p>
<div class="tmd-usual">
So Go specification doesn't specify the exact alignment guarantees for any types. It just specifies some minimal requirements.
</div>
<p></p>
<div class="tmd-usual">
For the same compiler, the exact type alignment guarantees may be different between different architectures and between different compiler versions. For the current version (v1.25.n) of the standard Go compiler, the alignment guarantees are listed here.
</div>
<p></p>
<pre class="tmd-code fixed-width">
<code class="language-go">type                      alignment guarantee
------                    ------
bool, uint8, int8         1
uint16, int16             2
uint32, int32             4
float32, complex64        4
arrays                    depend on element types
structs                   depend on field types
other types               size of a native word
</code></pre>
<p></p>
<div class="tmd-usual">
Here, the size of a native word (or machine word) is 4-byte on 32-bit architectures and 8-byte on 64-bit architectures.
</div>
<p></p>
<p></p>
<div class="tmd-usual">
This means, for the current version of the standard Go compiler, the alignment guarantees of other types may be either <code class="tmd-code-span">4</code> or <code class="tmd-code-span">8</code>, depends on different build target architectures. This is also true for gccgo.
</div>
<p></p>
<div class="tmd-usual">
Generally, we don't need to care about the value address alignments in Go programming, except that we want to optimizing memory consumption, or write portable programs which using the 64-bit functions from <code class="tmd-code-span">sync/atomic</code> package. Please read the following two sections for details.
</div>
<p></p>
<h3 id="size-and-padding" class="tmd-header-3">
Type Sizes and Structure Padding
</h3>
<p></p>
<div class="tmd-usual">
Go specification only makes following <a href="https://golang.org/ref/spec#Size_and_alignment_guarantees">type size guarantees</a>:
</div>
<pre class="tmd-code fixed-width">
<code class="language-go">type                    size in bytes
------                  ------
uint8, int8             1
uint16, int16           2
uint32, int32, float32  4
uint64, int64           8
float64, complex64      8
complex128              16
uint, int               implementation-specific,
                        generally 4 on 32-bit
                        architectures, and 8 on
                        64-bit architectures.
uintptr                 implementation-specific,
                        large enough to store
                        the uninterpreted bits
                        of a pointer value.
</code></pre>
<p></p>
<div class="tmd-usual">
Go specification doesn't make value size guarantees for other kinds of types. The full list of sizes of different types settled by the standard Go compiler are listed in <a href="value-copy-cost.html#value-sizes">value copy costs</a>.
</div>
<p></p>
<p></p>
<div class="tmd-usual">
The standard Go compiler (and gccgo) will ensure the size of values of a type is a multiple of the alignment guarantee of the type.
</div>
<p></p>
<div class="tmd-usual">
To satisfy type alignment guarantee rules mentioned previously, Go compilers may pad some bytes between fields of struct values. This makes the value size of a struct type may be not a simple sum of the sizes of all fields of the type.
</div>
<p></p>
<div class="tmd-usual">
The following is an example showing how bytes are padded between struct fields. We have already learned that
</div>
<ul class="tmd-list">
<li class="tmd-list-item">
<div class="tmd-usual">
the alignment guarantee and size of the built-in type <code class="tmd-code-span">int8</code> are both one byte.
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
the alignment guarantee and size of the built-in type <code class="tmd-code-span">int16</code> are both two bytes.
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
the size of the built-in type <code class="tmd-code-span">int64</code> is 8 bytes, the alignment guarantee of type <code class="tmd-code-span">int64</code> is 4 bytes on 32-bit architectures and 8 bytes on 64-bit architectures.
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
the alignment guarantees of the types <code class="tmd-code-span">T1</code> and <code class="tmd-code-span">T2</code> are their respective largest field alignment guarantees, a.k.a., the alignment guarantee of the <code class="tmd-code-span">int64</code> field. So their alignment guarantees are both 4 bytes on 32-bit architectures and 8 bytes on 64-bit architectures.
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
the sizes of the types <code class="tmd-code-span">T1</code> and <code class="tmd-code-span">T2</code> must be multiples of their respective alignment guarantees, a.k.a., 4N bytes on 32-bit architectures and 8N bytes on 64-bit architectures.
</div>
</li>
</ul>
<p></p>
<pre class="tmd-code line-numbers">
<code class="language-go">type T1 struct {
	a int8

	// On 64-bit architectures, to make field b
	// 8-byte aligned, 7 bytes need to be padded
	// here. On 32-bit architectures, to make
	// field b 4-byte aligned, 3 bytes need to be
	// padded here.

	b int64
	c int16

	// To make the size of type T1 be a multiple
	// of the alignment guarantee of T1, on 64-bit
	// architectures, 6 bytes need to be padded
	// here, and on 32-bit architectures, 2 bytes
	// need to be padded here.
}
// The size of T1 is 24 (= 1 + 7 + 8 + 2 + 6)
// bytes on 64-bit architectures and is 16
// (= 1 + 3 + 8 + 2 + 2) on 32-bit architectures.

type T2 struct {
	a int8

	// To make field c 2-byte aligned, one byte
	// needs to be padded here on both 64-bit
	// and 32-bit architectures.

	c int16

	// On 64-bit architectures, to make field b
	// 8-byte aligned, 4 bytes need to be padded
	// here. On 32-bit architectures, field b is
	// already 4-byte aligned, so no bytes need
	// to be padded here.

	b int64
}
// The size of T2 is 16 (= 1 + 1 + 2 + 4 + 8)
// bytes on 64-bit architectures, and is 12
// (= 1 + 1 + 2 + 8) on 32-bit architectures.
</code></pre>
<p></p>
<div class="tmd-usual">
Although <code class="tmd-code-span">T1</code> and <code class="tmd-code-span">T2</code> have the same field set, their sizes are different.
</div>
<p></p>
<div class="tmd-usual">
One interesting fact for the standard Go compiler is that sometimes zero sized fields may affect structure padding. Please read <a href="unofficial-faq.html#final-zero-size-field">this question in the unofficial Go FAQ</a> for details.
</div>
<p></p>
<p></p>
<h3 class="tmd-header-3">
The Alignment Requirement for 64-bit Word Atomic Operations
</h3>
<p></p>
<div class="tmd-usual">
<span class="tmd-bold"><span class="tmd-italic">64-bit words</span></span> mean values of types whose underlying types are <code class="tmd-code-span">int64</code> or <code class="tmd-code-span">uint64</code>.
</div>
<p></p>
<div class="tmd-usual">
The article <a href="concurrent-atomic-operation.html">atomic operations</a> mentions a fact that 64-bit atomic operations on a 64-bit word require the address of the 64-bit word must be 8-byte aligned. This is not a problem for the current 64-bit architectures supported by the standard Go compiler, because 64-bit words on these 64-bit architectures are always 8-byte aligned.
</div>
<p></p>
<p></p>
<div class="tmd-usual">
However, on 32-bit architectures, the alignment guarantee made by the standard Go compiler for 64-bit words is only 4 bytes. 64-bit atomic operations on a 64-bit word which is not 8-byte aligned will panic at runtime. Worse, on very old CPU architectures, 64-bit atomic functions are not supported.
</div>
<p></p>
<div class="tmd-usual">
At the end of the <a href="https://golang.org/pkg/sync/atomic/#pkg-note-BUG"><code class="tmd-code-span">sync/atomic</code> documentation</a>, it mentions:
</div>
<div class="tmd-quotation">
<div class="tmd-usual">
On x86-32, the 64-bit functions use instructions unavailable before the Pentium MMX.<br/><br/>On non-Linux ARM, the 64-bit functions use instructions unavailable before the ARMv6k core.<br/><br/>On both ARM and x86-32, it is the caller's responsibility to arrange for 64-bit alignment of 64-bit words accessed atomically. The first word in a variable or in an allocated struct, array, or slice can be relied upon to be 64-bit aligned.
</div>
</div>
<p></p>
<p></p>
<p></p>
<div class="tmd-usual">
So, things are not very bad for two reasons.
</div>
<ol class="tmd-list">
<li class="tmd-list-item">
<div class="tmd-usual">
The very old CPU architectures are not mainstream architectures nowadays. If a program needs to do synchronization for 64-bit words on these architectures, there are <a href="concurrent-synchronization-more.html">other synchronization techniques</a> to rescue.
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
On other not-very-old 32-bit architectures, there are some ways to ensure some 64-bit words are relied upon to be 64-bit aligned.
</div>
</li>
</ol>
<p></p>
<p></p>
<div class="tmd-usual">
The ways are described as <span class="tmd-bold">the first (64-bit) word in a variable or in an allocated struct, array, or slice can be relied upon to be 64-bit aligned</span>. What does the word <span class="tmd-bold"><span class="tmd-italic">allocated</span></span> mean? We can think an <span class="tmd-bold"><span class="tmd-italic">allocated value</span></span> as a <span class="tmd-bold"><span class="tmd-italic">declared</span></span> variable, a value returned by the built-in <code class="tmd-code-span">make</code> function, or the value referenced by a value returned by the built-in <code class="tmd-code-span">new</code> function. If a slice value derives from an allocated array and the first element of the slice is the first element of the array, then the slice value can also be viewed as an allocated value.
</div>
<p></p>
<div class="tmd-usual">
The description of which 64-bit words can be relied upon to be 64-bit aligned on 32-bit architectures is some conservative. There are more 64-bit words which can be relied upon to be 8-byte aligned. In fact, if the first element of an array or slice which element type is a 64-bit word type can be relied upon to be 64-bit aligned, then all elements in the array/slice can also be accessed atomically. It is just some subtle and verbose to make a simple clear description to include all the 64-bit words can be relied upon to be 64-bit aligned on 32-bit architectures, so the official documentation just makes a conservative description.
</div>
<p></p>
<p></p>
<div class="tmd-usual">
Here is an example which lists some 64-bit words which are safe or unsafe to be accessed atomically on both 64-bit and 32-bit architectures.
</div>
<p></p>
<pre class="tmd-code line-numbers">
<code class="language-go">type (
	T1 struct {
		v uint64
	}

	T2 struct {
		_ int16
		x T1
		y *T1
	}

	T3 struct {
		_ int16
		x [6]int64
		y *[6]int64
	}
)

var a int64    // a is safe
var b T1       // b.v is safe
var c [6]int64 // c[0] is safe

var d T2 // d.x.v is unsafe
var e T3 // e.x[0] is unsafe

func f() {
	var f int64           // f is safe
	var g = []int64{5: 0} // g[0] is safe

	var h = e.x[:] // h[0] is unsafe

	// Here, d.y.v and e.y[0] are both safe,
	// for *d.y and *e.y are both allocated.
	d.y = new(T1)
	e.y = &amp;[6]int64{}

	_, _, _ = f, g, h
}

// In fact, all elements in c, g and e.y.v are
// safe to be accessed atomically, though Go
// official documentation never makes the guarantees.
</code></pre>
<p></p>
<div class="tmd-usual">
If a 64-bit word field (generally the first one) of a struct type will be accessed atomically in code, we should always use allocated values of the struct type to guarantee the atomically accessed fields always can be relied upon to be 8-byte aligned on 32-bit architectures. When this struct type is used as the type of a field of another struct type, we should arrange the field as the first field of the other struct type, and always use allocated values of the other struct type.
</div>
<p></p>
<div class="tmd-usual">
Sometimes, if we can't make sure whether or not a 64-bit word can be accessed atomically, we can use a value of type <code class="tmd-code-span">[15]byte</code> to determine the address for the 64-bit word at run time. For example,
</div>
<p></p>
<pre class="tmd-code line-numbers">
<code class="language-go">package mylib

import (
	"unsafe"
	"sync/atomic"
)

type Counter struct {
	x [15]byte // instead of "x uint64"
}

func (c *Counter) xAddr() *uint64 {
	// The return must be 8-byte aligned.
	return (*uint64)(unsafe.Pointer(
		(uintptr(unsafe.Pointer(&amp;c.x)) + 7)/8*8))
}

func (c *Counter) Add(delta uint64) {
	p := c.xAddr()
	atomic.AddUint64(p, delta)
}

func (c *Counter) Value() uint64 {
	return atomic.LoadUint64(c.xAddr())
}
</code></pre>
<p></p>
<div class="tmd-usual">
By using this solution, the <code class="tmd-code-span">Counter</code> type can be embedded in other user types freely and safely, even on 32-bit architectures. The drawback of this solution is there are seven bytes being wasted for every value of <code class="tmd-code-span">Counter</code> type and it uses unsafe pointers.
</div>
<p></p>
<p></p>
<p></p>
<div class="tmd-usual">
Go 1.19 introduced a more elegant way to guarantee 8-byte alignments for some values. Go 1.19 added <a href="concurrent-atomic-operation.html#overview-1.19">several atomic types</a> in the <code class="tmd-code-span">sync/atomic</code> standard package. The types include <code class="tmd-code-span">atomic.Int64</code> and <code class="tmd-code-span">atomic.Uint64</code>, which values are guaranteed to be 8-byte aligned, even on 32-bit architectures. We may make use of this fact to make some 64-bit words always 8-byte aligned on 32-bit architectures. For example, in the following code, the <code class="tmd-code-span">x</code> field of any value of the type <code class="tmd-code-span">T</code> is always 8-byte aligned, in any situations, either on 64-bit or 32-bit architectures.
</div>
<p></p>
<pre class="tmd-code line-numbers">
<code class="language-go">type T struct {
	_ [0]atomic.Int64
	x int64
}
</code></pre>
<p></p>
</div>
